Skip to main content

Compatible Add-ons Selector

The Compatible add-ons block lets shoppers add related products from the main product form without leaving the product page. It works for accessories, add-ons, replacement parts, care kits, companion products, or any other items that should be easy to add alongside the main product.

Use this when the add-on should be purchased with the main product but should still remain its own normal Shopify cart line.

Create this product metafield in Shopify:

  • custom.compatible_accessories Type: Product list (list.product_reference)

Recommended usage:

  • Add the compatible products to custom.compatible_accessories on each parent product.
  • Keep accessory products published and available in the Online Store sales channel.
  • Use clear product titles and variant names, because those are shown in the add-ons picker and selected list.

You can also select products manually in the block if you do not want to use metafields.

Theme editor setup​

  1. Open the product template in the theme editor.
  2. Open the Buy buttons block.
  3. Add the Compatible add-ons block.
  4. Connect Compatible products to product.metafields.custom.compatible_accessories.
  5. Update the heading, or keep the default Add compatible items text.
  6. Adjust display options such as thumbnails, thumbnail size, row gap, border radius, margins, and padding.

Tip: avoid adding the parent product to its own compatible products list. The block skips the current product automatically, but keeping the metafield clean makes future maintenance easier.

Storefront behavior​

  • If no compatible products are configured, the block renders nothing.
  • Shoppers can select accessory variants, set quantities, and add multiple choices to a compact selected list.
  • Duplicate variant selections merge into one selected line with a higher quantity.
  • The parent product is added first. Compatible items are added only after the parent product add succeeds.
  • Compatible items are normal independent cart lines. Removing or changing the parent cart item does not automatically affect them.
  • Accelerated checkout is hidden while compatible items are selected so those selections are not bypassed.

Good use cases​

  • Hat accessories, replacement parts, care kits, or optional supplies.
  • Product bundles where each item still needs separate inventory, pricing, and fulfillment.
  • Recommended companion products that should be added from the product page instead of sending the shopper to another page.

Launch checklist​

  • The parent product has compatible products selected manually or through custom.compatible_accessories.
  • Each add-on product is published and has at least one available variant.
  • Product and variant names are clear enough for the compact selector.
  • The main add-to-cart button adds the parent product first, then the selected add-ons.
  • The cart displays the add-ons as separate products with the expected quantities.

Troubleshooting​

The block does not appear​

Confirm the product has compatible products selected in the block or a populated custom.compatible_accessories metafield. The block intentionally hides itself when the list is empty.

An add-on cannot be added​

Confirm the selected accessory variant is available, published, and available in the Online Store sales channel.

Accelerated checkout disappears​

That is expected while add-ons are selected. Customers should use the main add-to-cart button so the parent product and selected add-ons are added together.